
<html><head>
<title>command_argst - flibs</title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.toc,UL.toc UL, UL.toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.section, LI.subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.requirements LI, UL.syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<! -- Generated from file 'command_args.man' by tcllib/doctools with format 'html'
   -->
<! -- Copyright &copy; 2016 Arjen Markus &lt;arjenmarkus at sourceforge dot net&gt;
   -->
<! -- CVS: $Id: command_args.html,v 1.1 2016/12/04 11:40:54 arjenmarkus Exp $ command_argst.n
   -->
<body><div class="doctools">
<h1 class="title">command_argst(n) 1.0  &quot;flibs&quot;</h1>
<div id="name" class="section"><h2><a name="name">Name</a></h2>
<p>command_argst - Handle command-line arguments</p>
</div>
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="toc">
<li class="section"><a href="#toc">Table Of Contents</a></li>
<li class="section"><a href="#synopsis">Synopsis</a></li>
<li class="section"><a href="#section1">Description</a></li>
<li class="section"><a href="#section2">ROUTINES</a></li>
<li class="section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="synopsis">
<ul class="syntax">
<li><a href="#1"><b class="cmd">call handle_command_options( options )</b></a></li>
<li><a href="#2"><b class="cmd">arg = optarg( var, type, short, long, description )</b></a></li>
<li><a href="#3"><b class="cmd">arg = optarg( type, short, long, description )</b></a></li>
<li><a href="#4"><b class="cmd">ignored = argument_ignored( indx )</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
<p>The <i class="term">command_args</i> module can automatically handle the command-line arguments that are passed to the program.
For example, if you run the test program like:</p>
<pre class="example">
    test_command_args --real 1.2 -l
</pre>
<p>it will set the variables <i class="term">real_var</i> and <i class="term">l_var</i> to respectively <i class="term">1.2</i> and <i class="term">.true.</i>. It will not
set the variable <i class="term">int_var</i>, but it will set the other two logical variables <i class="term">m_var</i> and <i class="term">n_var</i> to <i class="term">.false.</i>,
because these are turned on by the options <i class="term">-m</i> and <i class="term">-n</i>.</p>
<p>The module supports the following types of command options:</p>
<ul class="itemized">
<li><p>Short options, consisting of a single letter, for instance: <i class="term">-i</i>. These options can be followed
by a value as the next argument: <i class="term">-i 12</i> or the value can be concatenated: <i class="term">-i12</i>.</p></li>
<li><p>If the option represents a logical value, then several options may be combined: <i class="term">-lmn</i> would
be interpreted as <i class="term">-l -m -n</i>. This is <em>only</em> for logical options.</p></li>
<li><p>Long options, consisting of an entire word, for instance: <i class="term">--integer</i>. These options can be
followed by a value as the next argument: <i class="term">--integer 12</i>. Concatenation is not supported though,
as it might lead to ambiguities.</p></li>
<li><p>Options to print usage information. If no explicit option is defined, then <i class="term">-h, -?</i> and <i class="term">--help</i>
will be used.</p></li>
<li><p>Options to stop processing further options. If no explicit option is defined, then <i class="term">--</i>
is used for this purpose.</p></li>
</ul>
<p>For each command argument it is possible to ask whether it was processed by the <i class="term">handle_command_options</i>
routine, so that special processing that is not covered by this routine, is made easier. To this end it
is also possible to define options that are explicitly ignored.</p>
</div>
<div id="section2" class="section"><h2><a name="section2">ROUTINES</a></h2>
<p>There are three public routines:</p>
<dl class="definitions">
<dt><a name="1"><b class="cmd">call handle_command_options( options )</b></a></dt>
<dd><p>This subroutine handles the command-line arguments as options defined in the array <i class="term">options</i>.
The entries of this array describe how options should be treated and - in many cases - which variables
should be set. See the description below</p>
<dl class="arguments">
<dt>type(cmd_options), dimension(:) <i class="arg">options</i></dt>
<dd><p>Description of the options.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd">arg = optarg( var, type, short, long, description )</b></a></dt>
<dd><p>This function returns a value of type <i class="term">cmd_option</i>, so that an array can be formed
to be passed to <i class="term">handle_command_options</i>. The argument <i class="term">var</i> is one of the basic types: integer,
single and double precision real, logical or a character string of any length.</p>
<dl class="arguments">
<dt>scalar <i class="arg">var</i></dt>
<dd><p>The variable to be assigned a value from the command-line arguments.</p></dd>
<dt>integer <i class="arg">type</i></dt>
<dd><p>The type of command-line argument:</p>
<ul class="itemized">
<li><p><i class="term">opt_value_next</i> is used to indicate that the next argument is the associated value</p></li>
<li><p><i class="term">opt_value_next</i> is used to indicate that the value is concatenated (for the short version of the
command-line argument) or that the next argument is the associated value (for the long version).</p></li>
<li><p><i class="term">opt_true</i> is used to indicate that the presence of this option means the associated logical variable
should be set to <i class="term">.true.</i>. If this option is not present, the variable is set to <i class="term">.false.</i>.</p></li>
<li><p><i class="term">opt_false</i> is used to indicate that the presence of this option means the associated logical variable
should be set to <i class="term">.false.</i>. If this option is not present, the variable is set to <i class="term">.true.</i>.</p></li>
</ul></dd>
<dt>character(len=1) <i class="arg">short</i></dt>
<dd><p>The one-letter short option. On the command line, such an option starts with &quot;-&quot;, but the dash is not given.</p></dd>
<dt>character(len=*) <i class="arg">long</i></dt>
<dd><p>The long option - on the command line, this should start with &quot;--&quot;. Only the word after the two dashes
should be specified.</p></dd>
<dt>character(len=*) <i class="arg">decription</i></dt>
<dd><p>A descriptive string which will be printed if the help option is used.</p></dd>
</dl></dd>
<dt><a name="3"><b class="cmd">arg = optarg( type, short, long, description )</b></a></dt>
<dd><p>This is a variant to be used if no variable is associated with the option.</p>
<dl class="arguments">
<dt>integer <i class="arg">type</i></dt>
<dd><p>The type of command-line argument:</p>
<ul class="itemized">
<li><p><i class="term">opt_help</i> is used to indicate that the usage information should be printed.</p></li>
<li><p><i class="term">opt_stop</i> is used to indicate that further arguments should not be examined.</p></li>
<li><p><i class="term">opt_ignore</i> is used to indicate that this argument should be ignored.</p></li>
<li><p><i class="term">opt_ignore_next</i> is used to indicate that this argument and the next should be ignored.</p></li>
</ul></dd>
<dt>character(len=1) <i class="arg">short</i></dt>
<dd><p>The one-letter short option. On the command line, such an option starts with &quot;-&quot;, but the dash is not given.</p></dd>
<dt>character(len=*) <i class="arg">long</i></dt>
<dd><p>The long option - on the command line, this should start with &quot;--&quot;. Only the word after the two dashes
should be specified.</p></dd>
<dt>character(len=*) <i class="arg">decription</i></dt>
<dd><p>A descriptive string which will be printed if the help option is used.</p></dd>
</dl></dd>
<dt><a name="4"><b class="cmd">ignored = argument_ignored( indx )</b></a></dt>
<dd><p>Use this function to find out if the argument was ignored during processing or not.</p>
<dl class="arguments">
<dt>integer <i class="arg">type</i></dt>
<dd><p>The index of the command-line argument:</p></dd>
</dl></dd>
</dl>
</div>
<div id="copyright" class="section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; 2016 Arjen Markus &lt;arjenmarkus at sourceforge dot net&gt;</p>
</div>
</div></body></html>